﻿#region Copyright Notice

//Copyright © 2007-2011, PARROT SA, all rights reserved. 

//DISCLAIMER 
//The APIs is provided by PARROT and contributors "AS IS" and any express or implied warranties, including, but not limited to, the implied warranties of merchantability 
//and fitness for a particular purpose are disclaimed. In no event shall PARROT and contributors be liable for any direct, indirect, incidental, special, exemplary, or 
//consequential damages (including, but not limited to, procurement of substitute goods or services; loss of use, data, or profits; or business interruption) however 
//caused and on any theory of liability, whether in contract, strict liability, or tort (including negligence or otherwise) arising in any way out of the use of this 
//software, even if advised of the possibility of such damage. 

//Author            : Wilke Jansoone
//Email             : wilke.jansoone@digitude.net
//Publishing date   : 28/11/2010 

//Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions
//are met:
//    - Redistributions of source code must retain the above copyright notice, this list of conditions, the disclaimer and the original author of the source code.
//    - Neither the name of the PixVillage Team, nor the names of its contributors may be used to endorse or promote products derived from this software without 
//      specific prior written permission.

#endregion

#region Imports

using System;
using Wilke.Interactive.Drone;

#endregion

namespace Wilke.Interactive.Drone.Contracts
{
    /// <summary>
    /// Provides a connection between an input device (e.g. Joystick) and an object that implements the <see cref="IDroneCommander">IDroneCommander</see> interface.
    /// </summary>
    public interface IInputProvider : IDisposable
    {
        #region Properties

        /// <summary>
        /// Gets or sets the instance that implements the <see cref="IDroneCommander">IDroneCommander</see> interface.
        /// </summary>
        /// <value>The object that implements the <see cref="IDroneCommander">IDroneCommander</see> interface.</value>
        IDroneCommander DroneCommander {get; set;}

        #endregion

        #region Methods

        /// <summary>
        /// Initializes the specified input provider.
        /// </summary>
        /// <returns>Returns <c>true</c> if the provider was initialized correclty; otherwise, <c>false</c>.</returns>
        /// <remarks>The throttling values are implicitly set to 1, so the values registered by the inputprovider will be passed unchanged to the object that implements the <see cref="IDroneCommander">IDroneCommander</see> interface.</remarks>
        bool Initialize();

        /// <summary>
        /// Initializes the specified input provider.
        /// </summary>
        /// <param name="rollThrottle">The roll throttle value between 0 and 1. The actual throttle value registered by the inputprovider will be multiplied by this value.</param>
        /// <param name="pitchThrottle">The pitch throttle value between 0 and 1. The actual pitch value registered by the inputprovider will be multiplied by this value.</param>
        /// <param name="heightThrottle">The height throttle value between 0 and 1. The actual height value registered by the inputprovider will be multiplied by this value.</param>
        /// <param name="yawThrottle">The yaw throttle value between 0 and 1. The actual yaw value registered by the inputprovider will be multiplied by this value.</param>
        /// <returns>Returns <c>true</c> if the provider was initialized correclty; otherwise, <c>false</c>.</returns>
        /// <remarks>The throttling is applied in order to be able to control the ARDrone in smaller places. A throttle value of 1 means that there is no throttling, a value of 0 means that the resulting value will also be 0.</remarks>
        bool Initialize(float rollThrottle, float pitchThrottle, float heightThrottle, float yawThrottle);

        #endregion
    }
}
